AOCODARCF7MINI_V1: DSHOT_DMAR and V1 output order
[inav.git] / docs / Programming Framework.md
blob9f95fdb25d52b12bd55efbc652b6a7a8318d402b
1 # INAV Programming Framework
3 INAV Programming Framework (IPF) is a mechanism that allows you to to create 
4 custom functionality in INAV. You can choose for certain actions to be done,
5 based on custom conditions you select.
7 Logic conditions can be based on things such as RC channel values, switches, altitude, 
8 distance, timers, etc. The conditions you create  can also make use of other conditions
9 you've entered previously.
10 The results can be used in:
12 * [Servo mixer](Mixer.md) to activate/deactivate certain servo mix rulers
13 * To activate/deactivate system overrides
15 INAV Programming Framework consists of:
17 * Logic Conditions - each Logic Condition can be understood as a single command, a single line of code. Each logic condition consists of:
18         * an operator (action), such as "plus" or "set vtx power"
19         * one or two operands (nouns), which the action acts upon. Operands are often numbers, such as a channel value or the distance to home.
20         * "activator" condition - optional. This condition is only active when another condition is true
21 * Global Variables - variables that can store values from and for Logic Conditions and servo mixer
22 * Programming PID - general purpose, user configurable PID controllers
24 IPF can be edited using INAV Configurator user interface, or via CLI. To use COnfigurator, click the tab labeled
25 "Programming". The various options shown in Configurator are described below.
27 ## Logic Conditions
29 ### CLI
31 `logic <rule> <enabled> <activatorId> <operation> <operand A type> <operand A value> <operand B type> <operand B value> <flags>`
33 * `<rule>` - ID of Logic Condition rule
34 * `<enabled>` - `0` evaluates as disabled, `1` evaluates as enabled
35 * `<activatorId>` - the ID of _LogicCondition_ used to activate this _Condition_. _Logic Condition_ will be evaluated only then Activator evaluates as `true`. `-1` evaluates as `true`
36 * `<operation>` - See `Operations` paragraph
37 * `<operand A type>` - See `Operands` paragraph
38 * `<operand A value>` - See `Operands` paragraph
39 * `<operand B type>` - See `Operands` paragraph
40 * `<operand B value>` - See `Operands` paragraph
41 * `<flags>` - See `Flags` paragraph
43 ### Operations
45 | Operation ID  | Name                          | Notes |
46 |---------------|-------------------------------|-------|
47 | 0             | TRUE                          | Always evaluates as true |
48 | 1             | EQUAL                         | Evaluates `false` if `false` or `0` |
49 | 2             | GREATER_THAN                  | `true` if `Operand A` is a higher value than `Operand B` |
50 | 3             | LOWER_THAN                    | `true` if `Operand A` is a lower value than `Operand B` |
51 | 4             | LOW                           | `true` if `<1333` |
52 | 5             | MID                           | `true` if `>=1333 and <=1666` |
53 | 6             | HIGH                          | `true` if `>1666` |
54 | 7             | AND                           | `true` if `Operand A` and `Operand B` are the same value or both `true` |
55 | 8             | OR                            | `true` if `Operand A` and/or `OperandB` is `true` |
56 | 9             | XOR                           | `true` if `Operand A` or `Operand B` is `true`, but not both |
57 | 10            | NAND                          | `false` if `Operand A` and `Operand B` are both `true`|
58 | 11            | NOR                           | `true` if `Operand A` and `Operand B` are both `false` |
59 | 12            | NOT                           | The boolean opposite to `Operand A` |         
60 | 13            | Sticky                        | `Operand A` is the activation operator, `Operand B` is the deactivation operator. After the activation is `true`, the operator will return `true` until Operand B is evaluated as `true`|         
61 | 14            | Basic: Add                           | Add `Operand A` to `Operand B` and returns the result |
62 | 15            | Basic: Subtract                           | Substract `Operand B` from `Operand A` and returns the result |
63 | 16            | Basic: Multiply                           | Multiply `Operand A` by `Operand B` and returns the result |
64 | 17            | Basic: Divide                           | Divide `Operand A` by `Operand B` and returns the result |
65 | 18            | Set GVAR                      | Store value from `Operand B` into the Global Variable addressed by
66 `Operand A`. Bear in mind, that operand `Global Variable` means: Value stored in Global Variable of an index! To store in GVAR 1 use `Value 1` not `Global Variable 1` |
67 | 19            | Increase GVAR                      | Increase the GVAR indexed by `Operand A` (use `Value 1` for Global Variable 1) with value from `Operand B`  |
68 | 20            | Decrease GVAR                      | Decrease the GVAR indexed by `Operand A` (use `Value 1` for Global Variable 1) with value from `Operand B`  |
69 | 21            | Set IO Port                   | Set I2C IO Expander pin `Operand A` to value of `Operand B`. `Operand A` accepts values `0-7` and `Operand B` accepts `0` and `1` |
70 | 22            | OVERRIDE_ARMING_SAFETY        | Allows the craft to arm on any angle even without GPS fix. WARNING: This bypasses all safety checks, even that the throttle is low, so use with caution. If you only want to check for certain conditions, such as arm without GPS fix. You will need to add logic conditions to check the throttle is low. |
71 | 23            | OVERRIDE_THROTTLE_SCALE       | Override throttle scale to the value defined by operand. Operand type `0` and value `50` means throttle will be scaled by 50%. |
72 | 24            | SWAP_ROLL_YAW                 | basically, when activated, yaw stick will control roll and roll stick will control yaw. Required for tail-sitters VTOL during vertical-horizonral transition when body frame changes |
73 | 25            | SET_VTX_POWER_LEVEL           | Sets VTX power level. Accepted values are `0-3` for SmartAudio and `0-4` for Tramp protocol |
74 | 26            | INVERT_ROLL                   | Inverts ROLL axis input for PID/PIFF controller |
75 | 27            | INVERT_PITCH                  | Inverts PITCH axis input for PID/PIFF controller  |
76 | 28            | INVERT_YAW                    | Inverts YAW axis input for PID/PIFF controller |
77 | 29            | OVERRIDE_THROTTLE             | Override throttle value that is fed to the motors by mixer. Operand is scaled in us. `1000` means throttle cut, `1500` means half throttle |
78 | 30            | SET_VTX_BAND                  | Sets VTX band. Accepted values are `1-5` |
79 | 31            | SET_VTX_CHANNEL               | Sets VTX channel. Accepted values are `1-8` |
80 | 32            | SET_OSD_LAYOUT                | Sets OSD layout. Accepted values are `0-3` |
81 | 33            | Trigonometry: Sine                           | Computes SIN of `Operand A` value in degrees. Output is multiplied by `Operand B` value. If `Operand B` is `0`, result is multiplied by `500` |
82 | 34            | Trigonometry: Cosine                           | Computes COS of `Operand A` value in degrees. Output is multiplied by `Operand B` value. If `Operand B` is `0`, result is multiplied by `500` |
83 | 35            | Trigonometry: Tangent                           | Computes TAN of `Operand A` value in degrees. Output is multiplied by `Operand B` value. If `Operand B` is `0`, result is multiplied by `500` |
84 | 36            | MAP_INPUT                     | Scales `Operand A` from [`0` : `Operand B`] to [`0` : `1000`]. Note: input will be constrained and then scaled |
85 | 37            | MAP_OUTPUT                    | Scales `Operand A` from [`0` : `1000`] to [`0` : `Operand B`]. Note: input will be constrained and then scaled |
86 | 38            | RC_CHANNEL_OVERRIDE           | Overrides channel set by `Operand A` to value of `Operand B`. Note operand A should normally be set as a "Value", NOT as "Get RC Channel"|
87 | 39            | SET_HEADING_TARGET            | Sets heading-hold target to `Operand A`, in degrees. Value wraps-around. |
88 | 40            | Modulo                           | Modulo. Divide `Operand A` by `Operand B` and returns the remainder |
89 | 41            | LOITER_RADIUS_OVERRIDE        | Sets the loiter radius to `Operand A` [`0` : `100000`] in cm. If the value is lower than the loiter radius set in the **Advanced Tuning**, that will be used. |
90 | 42            | SET_PROFILE                   | Sets the active config profile (PIDFF/Rates/Filters/etc) to `Operand A`. `Operand A` must be a valid profile number, currently from 1 to 3. If not, the profile will not change |
91 | 43            | Use Lowest Value                           | Finds the lowest value of `Operand A` and `Operand B` |
92 | 44            | Use Highest Value                           | Finds the highest value of `Operand A` and `Operand B` |
93 | 45                    | FLIGHT_AXIS_ANGLE_OVERRIDE    | Sets the target attitude angle for axis. In other words, when active, it enforces Angle mode (Heading Hold for Yaw) on this axis (Angle mode does not have to be active). `Operand A` defines the axis: `0` - Roll, `1` - Pitch, `2` - Yaw. `Operand B` defines the angle in degrees |
94 | 46                    | FLIGHT_AXIS_RATE_OVERRIDE         | Sets the target rate (rotation speed) for axis. `Operand A` defines the axis: `0` - Roll, `1` - Pitch, `2` - Yaw. `Operand B` defines the rate in degrees per second |
95 | 47            | EDGE                          | Momentarily true when triggered by `Operand A`. `Operand A` is the activation operator [`boolean`], `Operand B` _(Optional)_ is the time for the edge to stay active [ms]. After activation, operator will return `true` until the time in Operand B is reached. If a pure momentary edge is wanted. Just leave `Operand B` as the default `Value: 0` setting. |
96 | 48            | DELAY                         | Delays activation after being triggered. This will return `true` when `Operand A` _is_ true, and the delay time in `Operand B` [ms] has been exceeded. |
97 | 49            | TIMER                         | A simple on - off timer. `true` for the duration of `Operand A` [ms]. Then `false` for the duration of `Operand B` [ms]. |
98 | 50            | DELTA                         | This returns `true` when the value of `Operand A` has changed by the value of `Operand B` or greater within 100ms. |
99 | 51            | APPROX_EQUAL                  | `true` if `Operand B` is within 1% of `Operand A`. |
100 | 52            | LED_PIN_PWM                   | Value `Operand A` from [`0` : `100`] starts PWM generation on LED Pin. See [LED pin PWM](LED%20pin%20PWM.md). Any other value stops PWM generation (stop to allow ws2812 LEDs updates in shared modes)|
102 ### Operands
104 | Operand Type  | Name                  | Notes |
105 |---------------|-----------------------|-------|
106 | 0             | VALUE                 | Value derived from `value` field |
107 | 1             | GET_RC_CHANNEL        | `value` points to RC channel number, indexed from 1 |
108 | 2             | FLIGHT                | `value` points to flight parameter table |
109 | 3             | FLIGHT_MODE           | `value` points to flight modes table |
110 | 4             | LC                    | `value` points to other logic condition ID |
111 | 5             | GVAR                  | Value stored in Global Variable indexed by `value`. `GVAR 1` means: value in GVAR 1 |
112 | 5             | PID                   | Output of a Programming PID indexed by `value`. `PID 1` means: value in PID 1 |
114 #### FLIGHT
116 | Operand Value | Name                          | Notes |
117 |---------------|-------------------------------|-------|
118 | 0             | ARM_TIMER                     | in `seconds` |
119 | 1             | HOME_DISTANCE                 | in `meters` |
120 | 2             | TRIP_DISTANCE                 | in `meters` |
121 | 3             | RSSI                          |  |
122 | 4             | VBAT                          | in `Volts * 100`, eg. `12.1V` is `1210` |
123 | 5             | CELL_VOLTAGE                  | in `Volts * 100`, eg. `12.1V` is `1210` |
124 | 6             | CURRENT                       | in `Amps * 100`, eg. `9A` is `900` |
125 | 7             | MAH_DRAWN                     | in `mAh`                              |
126 | 8             | GPS_SATS                      |  |
127 | 9             | GROUD_SPEED                   | in `cm/s` |
128 | 10            | 3D_SPEED                      | in `cm/s` |
129 | 11            | AIR_SPEED                     | in `cm/s` |
130 | 12            | ALTITUDE                      | in `cm` |
131 | 13            | VERTICAL_SPEED                | in `cm/s` |
132 | 14            | TROTTLE_POS                   | in `%` |
133 | 15            | ATTITUDE_ROLL                 | in `degrees` |
134 | 16            | ATTITUDE_PITCH                | in `degrees` |
135 | 17            | IS_ARMED                      | boolean `0`/`1` |
136 | 18            | IS_AUTOLAUNCH                 | boolean `0`/`1` |
137 | 19            | IS_ALTITUDE_CONTROL           | boolean `0`/`1` |
138 | 20            | IS_POSITION_CONTROL           | boolean `0`/`1` |
139 | 21            | IS_EMERGENCY_LANDING          | boolean `0`/`1` |
140 | 22            | IS_RTH                        | boolean `0`/`1` |
141 | 23            | IS_LANDING                    | boolean `0`/`1` |
142 | 24            | IS_FAILSAFE                   | boolean `0`/`1` |
143 | 25            | STABILIZED_ROLL               | Roll PID controller output `[-500:500]` |
144 | 26            | STABILIZED_PITCH              | Pitch PID controller output `[-500:500]` |
145 | 27            | STABILIZED_YAW                | Yaw PID controller output `[-500:500]` |
146 | 28            | 3D HOME_DISTANCE              | in `meters`, calculated from HOME_DISTANCE and ALTITUDE using Pythagorean theorem |
147 | 29            | CROSSFIRE LQ                  | Crossfire Link quality as returned by the CRSF protocol | 
148 | 30            | CROSSFIRE SNR                 | Crossfire SNR as returned by the CRSF protocol |
149 | 31            | GPS_VALID                     | boolean `0`/`1`. True when the GPS has a valid 3D Fix |
150 | 32            | LOITER_RADIUS                 | The current loiter radius in cm. |
151 | 33            | ACTIVE_PROFILE                | integer for the active config profile `[1..MAX_PROFILE_COUNT]` |
152 | 34            | BATT_CELLS                    | Number of battery cells detected |
153 | 35            | AGL_STATUS                    | boolean `1` when AGL can be trusted, `0` when AGL estimate can not be trusted |
154 | 36            | AGL                           | integer Above The Groud Altitude in `cm` |
155 | 37            | RANGEFINDER_RAW               | integer raw distance provided by the rangefinder in `cm` |
156 | 38            | ACTIVE_MIXER_PROFILE          | Which mixers are currently active (for vtol etc) |
157 | 39            | MIXER_TRANSITION_ACTIVE       | Currently switching between mixers (quad to plane etc) |
158 | 40            | ATTITUDE_YAW                  | current heading (yaw) in `degrees` |
159 | 41            | FW Land Sate                  | integer `1` - `5`, indicates the status of the FW landing, 0 Idle, 1 Downwind, 2 Base Leg, 3 Final Approach, 4 Glide, 5 Flare |
161 #### FLIGHT_MODE
163 The flight mode operands return `true` when the mode is active. These are modes that you will see in the **Modes** tab. Note: the `USER*` modes are used by camera switchers, PINIO etc. They are not the Waypoint User Actions. See the [Waypoints](#waypoints) section to access those.
165 | Operand Value | Name              | Notes |
166 |---------------|-------------------|-------|
167 | 0             | FAILSAFE          | `true` when a **Failsafe** state has been triggered. |
168 | 1             | MANUAL            | `true` when you are in the **Manual** flight mode. |
169 | 2             | RTH               | `true` when you are in the **Return to Home** flight mode. |
170 | 3             | POSHOLD           | `true` when you are in the **Position Hold** or **Loiter** flight modes. |
171 | 4             | CRUISE            | `true` when you are in the **Cruise** flight mode. |
172 | 5             | ALTHOLD           | `true` when you the **Altitude Hold** flight mode modifier is active. |
173 | 6             | ANGLE             | `true` when you are in the **Angle** flight mode. |
174 | 7             | HORIZON           | `true` when you are in the **Horizon** flight mode. |
175 | 8             | AIR               | `true` when you the **Airmode** flight mode modifier is active. |
176 | 9             | USER1             | `true` when the **USER 1** mode is active. |
177 | 10            | USER2             | `true` when the **USER 2** mode is active. |
178 | 11            | COURSE_HOLD       | `true` when you are in the **Course Hold** flight mode. |
179 | 12            | USER3             | `true` when the **USER 3** mode is active. |
180 | 13            | USER4             | `true` when the **USER 4** mode is active. |
181 | 14            | ACRO              | `true` when you are in the **Acro** flight mode. |
182 | 15            | WAYPOINT_MISSION  | `true` when you are in the **WP Mission** flight mode. | 
184 #### WAYPOINTS
186 | Operand Value | Name                          | Notes |
187 |---------------|-------------------------------|-------|
188 | 0             | Is WP                         | Boolean `0`/`1` |
189 | 1             | Current Waypoint Index        | Current waypoint leg. Indexed from `1`. To verify WP is in progress, use `Is WP` |
190 | 2             | Current Waypoint Action       | `true` when Action active in current leg. See ACTIVE_WAYPOINT_ACTION table |
191 | 3             | Next Waypoint Action          | `true` when Action active in next leg. See ACTIVE_WAYPOINT_ACTION table |
192 | 4             | Distance to next Waypoint     | Distance to next WP in metres |
193 | 5             | Distance from Waypoint        | Distance from the last WP in metres |
194 | 6             | User Action 1                 | `true` when User Action 1 is active on this waypoint leg [boolean `0`/`1`] |
195 | 7             | User Action 2                 | `true` when User Action 2 is active on this waypoint leg [boolean `0`/`1`] |
196 | 8             | User Action 3                 | `true` when User Action 3 is active on this waypoint leg [boolean `0`/`1`] |
197 | 9             | User Action 4                 | `true` when User Action 4 is active on this waypoint leg [boolean `0`/`1`] |
198 | 10            | Next Waypoint User Action 1   | `true` when User Action 1 is active on the next waypoint leg [boolean `0`/`1`] |
199 | 11            | Next Waypoint User Action 2   | `true` when User Action 2 is active on the next waypoint leg [boolean `0`/`1`] |
200 | 12            | Next Waypoint User Action 3   | `true` when User Action 3 is active on the next waypoint leg [boolean `0`/`1`] |
201 | 13            | Next Waypoint User Action 4   | `true` when User Action 4 is active on the next waypoint leg [boolean `0`/`1`] |
204 #### ACTIVE_WAYPOINT_ACTION
206 | Action        | Value |
207 |---------------|-------|
208 | WAYPOINT      | 1     |
209 | HOLD_TIME     | 3     |
210 | RTH           | 4     |
211 | SET_POI       | 5     |
212 | JUMP          | 6     |
213 | SET_HEAD      | 7     |
214 | LAND          | 8     |
215     
216 ### Flags
218 All flags are reseted on ARM and DISARM event.
220 | bit   | Decimal   | Function  |
221 |-------|-----------|-----------|
222 | 0     | 1         | Latch - after activation LC will stay active until LATCH flag is reset |
223 | 1     | 2         | Timeout satisfied - Used in timed operands to determine if the timeout has been met |
225 ## Global variables
227 ### CLI
229 `gvar <index> <default value> <min> <max>`
231 ## Programming PID
233 `pid <index> <enabled> <setpoint type> <setpoint value> <measurement type> <measurement value> <P gain> <I gain> <D gain> <FF gain>`
235 * `<index>` - ID of PID Controller, starting from `0`
236 * `<enabled>` - `0` evaluates as disabled, `1` evaluates as enabled
237 * `<setpoint type>` - See `Operands` paragraph
238 * `<setpoint value>` - See `Operands` paragraph
239 * `<measurement type>` - See `Operands` paragraph
240 * `<measurement value>` - See `Operands` paragraph
241 * `<P gain>` - P-gain, scaled to `1/1000`
242 * `<I gain>` - I-gain, scaled to `1/1000`
243 * `<D gain>` - D-gain, scaled to `1/1000`
244 * `<FF gain>` - FF-gain, scaled to `1/1000`
246 ## Examples
248 ### When more than 100 meters away, increase VTX power
249 ![screenshot of vtx home distance](./assets/images/vtx_home_distance.png)
251 ### When more than 600 meters away, engage return-to-home by setting the matching RC channel
252 ![screenshot of rth home distance](./assets/images/rth_home_distance.jpg)
255 ### Dynamic THROTTLE scale
257 `logic 0 1 0 23 0 50 0 0 0`
259 Limits the THROTTLE output to 50% when Logic Condition `0` evaluates as `true`
261 ### Set VTX power level via Smart Audio
263 `logic 0 1 0 25 0 3 0 0 0`
265 Sets VTX power level to `3` when Logic Condition `0` evaluates as `true`
267 ### Invert ROLL and PITCH when rear facing camera FPV is used
269 Solves the problem from [https://github.com/iNavFlight/inav/issues/4439](https://github.com/iNavFlight/inav/issues/4439)
272 logic 0 1 0 26 0 0 0 0 0
273 logic 1 1 0 27 0 0 0 0 0
276 Inverts ROLL and PITCH input when Logic Condition `0` evaluates as `true`. Moving Pitch stick up will cause pitch down (up for rear facing camera). Moving Roll stick right will cause roll left of a quad (right in rear facing camera)
278 ### Cut motors but keep other throttle bindings active
280 `logic 0 1 0 29 0 1000 0 0 0`
282 Sets throttle output to `0%` when Logic Condition `0` evaluates as `true`
284 ### Set throttle to 50% and keep other throttle bindings active
286 `logic 0 1 0 29 0 1500 0 0 0`
288 Sets throttle output to about `50%` when Logic Condition `0` evaluates as `true`
290 ### Set throttle control to different RC channel
292 `logic 0 1 0 29 1 7 0 0 0`
294 If Logic Condition `0` evaluates as `true`, motor throttle control is bound to RC channel 7 instead of throttle channel
296 ### Set VTX channel with a POT
298 Set VTX channel with a POT on the radio assigned to RC channel 6
301 logic 0 1 -1 15 1 6 0 1000 0
302 logic 1 1 -1 37 4 0 0 7 0
303 logic 2 1 -1 14 4 1 0 1 0
304 logic 3 1 -1 31 4 2 0 0 0
307 Steps:
308 1. Normalize range `[1000:2000]` to `[0:1000]` by substracting `1000`
309 2. Scale range `[0:1000]` to `[0:7]`
310 3. Increase range by `1` to have the range of `[1:8]`
311 4. Assign LC#2 to VTX channel function
313 ### Set VTX power with a POT
315 Set VTX power with a POT on the radio assigned to RC channel 6. In this example we scale POT to 4 power level `[1:4]`
318 logic 0 1 -1 15 1 6 0 1000 0
319 logic 1 1 -1 37 4 0 0 3 0
320 logic 2 1 -1 14 4 1 0 1 0
321 logic 3 1 -1 25 4 2 0 0 0
324 Steps:
325 1. Normalize range [1000:2000] to [0:1000] by substracting `1000`
326 2. Scale range [0:1000] to [0:3]
327 3. Increase range by `1` to have the range of [1:4]
328 4. Assign LC#2 to VTX power function
330 ## Common issues / questions about IPF
332 One common mistake involves setting RC channel values. To override (set) the 
333 value of a specific RC channel, choose "Override RC value", then for operand A
334 choose *value* and enter the channel number. Choosing "get RC value" is a common mistake,
335 which does something other than what you probably want.
337 ![screenshot of override an RC channel with a value](./assets/images/ipf_set_get_rc_channel.png)